<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Ranges</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Bytevectors.xhtml" title="Bytevectors"/>
    <link rel="next" href="Streams.xhtml" title="Streams - lazy lists"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Ranges" epub:type="subchapter" id="Ranges">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Ranges</h2>
          </div>
        </div>
      </div>
      <p>A <em class="firstterm">range</em> is an immutable sequence of values
that increase “linearly” - i.e. by a fixed amount.
Most commonly it’s a sequence of consequtive integers.
An example of the syntax is <code class="literal">[3 &lt;: 7]</code> which evaluates
to the sequence <code class="literal">[3 4 5 6]</code>.
You can specify an explicit increment with a <code class="literal">by:</code> option.
There are multiple ways to specify when the sequence stops.
For example <code class="literal">[3 by 2 &lt;=: 7]</code> is the even numbers from
3 up to 7 (inclusive, because of the <code class="literal">&lt;=</code>).
</p>
      <p>Ranges are very useful for loop indexes, or selecting a sub-sequence.
If you have a sequence <em class="replaceable"><code>q</code></em> and a range <em class="replaceable"><code>r</code></em>, and you
use the syntax <code class="literal">(<em class="replaceable"><code>q</code></em> <em class="replaceable"><code>r</code></em>)</code> to
“apply”<em class="replaceable"><code>q</code></em> with the argument <em class="replaceable"><code>r</code></em>,
is result is to select elements of <em class="replaceable"><code>q</code></em> with indexes in <em class="replaceable"><code>r</code></em>.
</p>
      <pre class="screen">("ABCDEFG" [1 by: 2 &lt;: 7])  ⇒ "BDF"
</pre>
      <p>A range can be <em class="firstterm">unbounded</em>, or non-finite, if you leave off
the end value.  For example <code class="literal">[3 by: 2]</code> is the odd integers starting at 3.
</p>
      <div class="literallayout">
        <p><a id="idm139667873926560" class="indexterm"/><span id="meta-unbounded-range"/><em class="replaceable"><code>unbounded-range</code></em> <code class="literal">::=</code><br/>
  <code class="literal"><span class="bold"><strong>[</strong></span></code> <em class="replaceable"><code>start-expression</code></em> <code class="literal"><span class="bold"><strong>by:</strong></span></code> <em class="replaceable"><code>step-expression</code></em> <code class="literal"><span class="bold"><strong>]</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>[</strong></span></code> <em class="replaceable"><code>start-expression</code></em> <code class="literal"><span class="bold"><strong>&lt;:</strong></span></code> <code class="literal"><span class="bold"><strong>]</strong></span></code><br/>
</p>
      </div>
      <p>The expression <code class="literal">[<em class="replaceable"><code>start</code></em> by: <em class="replaceable"><code>step</code></em>]</code> evaluates to an
infinite sequence of values, starting with <em class="replaceable"><code>start</code></em>, and followed by
<code class="literal">(+ <em class="replaceable"><code>start</code></em> <em class="replaceable"><code>step</code></em>)</code>,
<code class="literal">(+ <em class="replaceable"><code>start</code></em> (* 2 <em class="replaceable"><code>step</code></em>))</code>, and so on.
</p>
      <p>The syntax <code class="literal">[<em class="replaceable"><code>start-expression</code></em> &lt;:]</code>
is shorthand for <code class="literal">[<em class="replaceable"><code>start-expression</code></em> by: 1]</code>.
</p>
      <div class="literallayout">
        <p><a id="idm139667873911504" class="indexterm"/><span id="meta-bounded-range"/><em class="replaceable"><code>bounded-range</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>[</strong></span></code> <em class="replaceable"><code>start-expression</code></em> [<code class="literal"><span class="bold"><strong>by:</strong></span></code> <em class="replaceable"><code>step-expression</code></em>] <a class="link" href="Ranges.xhtml#meta-range-end"><em class="replaceable"><code>range-end</code></em></a> <code class="literal"><span class="bold"><strong>]</strong></span></code><br/>
<a id="idm139667873905520" class="indexterm"/><span id="meta-range-end"/><em class="replaceable"><code>range-end</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>&lt;:</strong></span></code> <em class="replaceable"><code>end-expression</code></em><br/>
  | <code class="literal"><span class="bold"><strong>&lt;=:</strong></span></code> <em class="replaceable"><code>end-expression</code></em><br/>
  | <code class="literal"><span class="bold"><strong>&gt;:</strong></span></code> <em class="replaceable"><code>end-expression</code></em><br/>
  | <code class="literal"><span class="bold"><strong>&gt;=:</strong></span></code> <em class="replaceable"><code>end-expression</code></em><br/>
  | <code class="literal"><span class="bold"><strong>size:</strong></span></code> <em class="replaceable"><code>size-expression</code></em><br/>
</p>
      </div>
      <p>A bounded range takes an initial subsequence of the unbounded
range specified by the <em class="replaceable"><code>start-expression</code></em> and optional <em class="replaceable"><code>step-expression</code></em>.
The different <em class="replaceable"><code>end-expression</code></em> variants provide different
ways to specify the initial subsequence.
</p>
      <p>If <code class="literal">size: <em class="replaceable"><code>size</code></em></code> is specified, then the resulting range
is the first <em class="replaceable"><code>size</code></em> elements of unbounded sequence.
</p>
      <p>In the <code class="literal">&lt;: <em class="replaceable"><code>end</code></em></code> or <code class="literal">&lt;=: <em class="replaceable"><code>end</code></em></code> cases then
the sequence counts up: The <em class="replaceable"><code>step</code></em> must be positive, and defaults to 1.
The resulting values are those  <em class="replaceable"><code>x</code></em> such that <code class="literal">(&lt; <em class="replaceable"><code>x</code></em> <em class="replaceable"><code>end</code></em>)</code>,
or  <code class="literal">(&lt;= <em class="replaceable"><code>x</code></em> <em class="replaceable"><code>end</code></em>)</code>, respectively.
</p>
      <p>In the <code class="literal">&gt;: <em class="replaceable"><code>end</code></em></code> or <code class="literal">&gt;=: <em class="replaceable"><code>end</code></em></code> cases then
the sequence counts down: The <em class="replaceable"><code>step</code></em> must be negative, and defaults to -1.
The resulting values are those  <em class="replaceable"><code>x</code></em> such that <code class="literal">(&gt; <em class="replaceable"><code>x</code></em> <em class="replaceable"><code>end</code></em>)</code>,
or  <code class="literal">(&gt;= <em class="replaceable"><code>x</code></em> <em class="replaceable"><code>end</code></em>)</code>, respectively.
</p>
      <p>The <em class="replaceable"><code>start-expression</code></em>, <em class="replaceable"><code>step-expression</code></em>, and <em class="replaceable"><code>size-expression</code></em>
must evaluate to real numbers, not necessarily integers.
For example: <code class="literal">[1 by: 0.5 &lt;=: 3.0]</code> is <code class="literal">[1.0 1.5 2.0 2.5 3.0]</code>.
</p>
      <p>The two pseudo-ranges <code class="literal">[&lt;:]</code> and <code class="literal">[&gt;:]</code> are useful as
array indexes. They mean “all of the valid indexes” of the array being indexed.
For increasing index values use <code class="literal">[&lt;:]</code>; for decreasing
index values (i.e. reversing) use <code class="literal">[&gt;:]</code>.
</p>
    </section>
    <footer>
      <div class="navfooter">
        <p>
          Up: <a accesskey="u" href="Data-structures.xhtml">Data structures</a></p>
        <p>
        Previous: <a accesskey="p" href="Bytevectors.xhtml">Bytevectors</a></p>
        <p>
        Next: <a accesskey="n" href="Streams.xhtml">Streams - lazy lists</a></p>
      </div>
    </footer>
  </body>
</html>
